<?php
/**
 * @author		João Batista Neto
 * @brief		Classes e interfaces relacionadas com o protocolo HTTP
 * @package		rpo.http
 */

/**
 * @brief		Definição de constantes para métodos de requisição HTTP.
 * @details		Segundo a especificação do protocolo HTTP/1.1, os métodos GET e HEAD
 * <b>NÃO DEVEM</b> ser utilizados para qualquer coisa que não seja recuperação de dados;
 * Esses métodos são chamados de <i>métodos seguros</i>; Isso permite ao user agent saber
 * como representar métodos como DELETE, POST, PUT de uma forma especial, alertando o
 * usuário sobre a possibilidade de uma ação "não segura", como reenviar dados que podem
 * estar relacionados com uma compra por exemplo.
 * @interface		HTTPRequestMethod
 */
interface HTTPRequestMethod {
	/**
	 * @brief		Método DELETE
	 * @details		O método DELETE solicita ao servidor para que exclua um determinado recurso
	 * identificado pela URI; Este método pode ser "sobrescrito" por intervensão humana ou
	 * qualquer outro meio no servidor. O cliente não pode ser garantido de que a operação foi
	 * realizada , mesmo que o código de status retornado indique que a ação foi realizada com
	 * sucesso.
	 * O servidor <b>deve</b> retornar:
	 * @li			200 Ok, para uma resposta bem sucedida.
	 * @li			202 Accepted, se a requisição ainda não foi aprovada.
	 * @li			204 No Content, se a requisição foi aprovada mas a resposta não contém conteúdo.
	 */
	const DELETE	= 'DELETE';

	/**
	 * @brief		Método GET
	 * @details		O método GET significa <b>recupere qualquer informação</b> identificada
	 * pela URI. Se a URI refere-se à um processo de produção de dados, os dados produzidos
	 * que deverão ser retornados na resposta e não o texto do processo, a não ser que o texto
	 * seja a saída do processo.
	 */
	const GET		= 'GET';

	/**
	 * @brief		Método HEAD
	 * @details		O método HEAD é idêntico ao método GET exceto que o método HEAD não deve
	 * retornar um corpo. Os cabeçalhos de uma requisição HEAD devem ser idênticos aos que
	 * seriam retornados em uma requisição GET. Este método pode ser utilizado para obter
	 * informações sobre um determinado recurso, sem precisar recuperar o recurso em si.
	 * Este método é utilizado também para teste de acessibilidade, validação e verificação
	 * sobre recentes modificações de um determinado recurso.
	 */
	const HEAD		= 'HEAD';

	/**
	 * @brief		Método POST
	 * @details		O método POST é projetado para cobrir as seguintes funções:
	 * @li			Anotação de recursos existentes.
	 * @li			Postar uma mensagem em um mural, sistema de notícias, lista de correio
	 * ou um grupo artigos.
	 * @li			Proporcionar um bloco de dados, como o resultado da submissão de um
	 * formulário para manipulação de dados.
	 * @li			Adicionar dados em uma base através do acréscimo de informações.
	 */
	const POST		= 'POST';

	/**
	 * @brief		Método PUT
	 * @details		O método PUT requisita que a entidade seja armazenada na URI especificada. Se o
	 * recurso já existir, a entidade deve ser considerada como uma versão modificada do recurso.
	 * Se o recurso não existir e a URI puder ser considerada como um novo recurso pelo servidor, o
	 * servidor poderá criar o novo recurso, nesse caso, o servidor deverá informar na resposta através
	 * do cabeçalho HTTP 201 (Created) que o novo recurso foi criado.
	 * A diferença fundamental entre o método PUT e o método POST está no significado da URI. Em um POST
	 * a URI identifica um recurso que irá manipular uma entidade; Esse recurso pode ser um processo
	 * de manipulação/aceitação de dados, um gateway para um outro serviço ou protocolo, já o método PUT
	 * identifica a entidade, o user agent sabe qual é o objetivo da URI e sabe também que o servidor
	 * não pode utilizar a requisição em qualquer outro recurso.
	 */
	const PUT		= 'PUT';
}